<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<style type="text/css"> /* <![CDATA[ */
  @import "tigris-branding/css/tigris.css";
  @import "tigris-branding/css/inst.css";
  /* ]]> */</style>
<link rel="stylesheet" type="text/css" media="print" href="tigris-branding/css/print.css"/>
<script type="text/javascript" src="tigris-branding/scripts/tigris.js"></script>
<title>SubEthaSMTP Mail Server</title>
<!-- Custom stylations to hide the obnoxious project info -->
<style type="text/css">
#apphead h1 { display: none; }
#customcontent h2 { display: block; }
</style>
<!-- End custom stylations -->
</head>

<body>
<!-- The class h2 is included on the main div, because the HTML which the
     server will wrap around the page includes a <div class="h2">.
     Thus, we include one here so that the page looks right when previewed
     locally, *but* we override the border which the CSS assigns to that
     style, so that we do not get two borders on the live page. -->
<div class="h2 app" style="border-left: 0px" id="customcontent">

<script type="text/javascript"><!--
google_ad_client = "pub-3899545862839569";
google_ad_width = 468;
google_ad_height = 60;
google_ad_format = "468x60_as";
google_ad_type = "text_image";
//2007-06-21: wide subethasmtp tigris.org
google_ad_channel = "6417060131";
google_color_border = "444400";
google_color_bg = "CCCC99";
google_color_link = "444400";
google_color_text = "3D81EE";
google_color_url = "FF0000";
//-->
</script>
<script type="text/javascript"
  src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
</script>

	<h2>SubEthaSMTP Mail Server</h2>
	
	<p>
		<a href="http://en.wikipedia.org/wiki/Sub-Etha">SubEtha</a>SMTP is
		an easy to understand Java library which provides a receptive 
		SMTP server component. By plugging this component into your 
		Java application, you can easily receive SMTP mail using a simple 
		but powerful abstract Java interface.
	</p>
	
	<p>
		This component can be used in almost any kind of email 
		processing application.  Hypothetical (and not-so hypothetical)
		uses include:
	</p>
	
	<ul>
		<li>A mailing list manager (ie, <a href="http://subetha.tigris.org/">SubEtha Mail</a>)</li>
		<li>A mail server that delivers mail to user inboxes</li>
		<li>A mail archiver like <a href="http://www.mail-archive.com/">Mail Archive</a></li>
		<li>An email test harness (Implemented in this project. It's called <a href="wiser.html">Wiser</a>.)</li>
	</ul>
	
	<p>
		SubEthaSMTP's simple, low-level API is suitable for writing almost
		any kind of mail-receiving application.
	</p>
	
	<h2>A Little History</h2>
	
	<p>
		SubEthaSMTP was split out of the
		<a href="http://subetha.tigris.org/">SubEtha Mail</a> mailing
		list manager because it is a useful standalone component.  When
		we wrote SubEtha, the last thing we wanted to do was write our
		own SMTP server.  In our search for a modular Java SMTP component,
		we examined:
	</p>
	
	<ul>
		<li><a href="http://james.apache.org/">Apache JAMES</a></li>
		<li><strike><a href="http://labs.jboss.com/portal/jbossmail/index.html">JBoss Mail Server</a></strike> - Now <a href="http://www.buni.org/mediawiki/index.php/Meldware_Mail">Meldware Mail</a></li>
		<li><a href="http://quintanasoft.com/dumbster/">Dumbster</a></li>
		<li><a href="http://www.jsmtpd.org/site/">Jsmtpd</a></li>
		<li><a href="http://www.ericdaugherty.com/java/mailserver/">JES</a></li>
		<li><a href="http://jmailsrv.sourceforge.net/">Java Mail Server</a></li>
		<li><a href="http://www.icegreen.com/greenmail/">Green Mail</a></li>
	</ul>
	
	<p>
		Since you're reading this page you probably already know what we found:
		Seven different SMTP implementations without the slightest thought
		given to reusability. Even Jstmpd, which purports to be a "A Modular
		Java SMTP Daemon", isn't.  Even though <strike>JBoss Mail</strike> 
		Meldware Mail is in active development, the team was unintersted in 
		componentization of the SMTP processing portion of their server. 
		GreenMail, which is based on the JAMES code base is best summarized with this 
		<a href="http://eokyere.blogspot.com/2006/10/get-wiser-with-subethasmtp.html">blog posting</a>.
	</p>

	<p>
		During the development of SubEtha's testing harness, we tried out
		the <a href="http://quintanasoft.com/dumbster/">Dumbster</a> software 
		and found that not only was the API difficult to use, it did it not work 
		properly, the developer has not done any development on it in about a 
		year and it does not work reliably on Mac OS X. With two simple classes
		we re-implemented it as an included project called <a href="wiser.html">Wiser</a>.
	</p>
	
	<p>
		We hate reinventing wheels.  This should be the LAST FREAKING JAVA
		SMTP IMPLEMENTATION.
	</p>

	<h2>Project Authors</h2>
	
	<p>
		Ian McFarland contributed the first codebase to SubEtha Mail. Then, Jon Stevens
		and Jeff Schnitzer re-wrote most of Ian's code into what we have today. Edouard De Oliveira
		and Scott Hernandez have also made significant contributions.
	</p>
	
	<h2>How To Get It</h2>
	
	<p>
		Head on down to the <a href="http://subethasmtp.tigris.org/servlets/ProjectDocumentList">Downloads section</a> or get the source code from 
		our <a href="http://subethasmtp.tigris.org/source/browse/subethasmtp/">Subversion repository</a>.
	</p>
	
	<h2>How To Use It</h2>
	
	<p>
		SubEthaSMTP depends only on the <a href="http://www.slf4j.org/">SLF4J</a> logging library.
		You will need <code>slf4j-api-X.X.X.jar</code> and one of the SLF4J binding jars such
		as <code>slf4j-simple-X.X.X.jar</code>, both of which are included in our distribution.
		Other binding jars (Log4J, java.util.logging, LogKit, etc) are available in the SLF4J distribution.
	</p>
	
	<p>
		Note that <a href="wiser.html">Wiser</a> has additional dependencies.
	</p>
	
	<p>
		SubEthaSMTP implements a powerful, low-level API that lets you handle incoming mail
		and (optionally) authenticate clients.  It also provides several helper classes that
		make life easier, if perhaps less flexible. 
	</p>	

	<h3>The Basic API</h3>

<pre>SMTPServer smtpServer = new SMTPServer(myFactory);
smtpServer.start();</pre>
	
<pre>public interface MessageHandlerFactory
{
	/**
	 * Called for the exchange of a single message during an SMTP conversation.
	 */
	public MessageHandler create(MessageContext ctx);
}

public interface MessageHandler
{
	/**
	 * Called first, after the MAIL FROM during a SMTP exchange.
	 */
	public void from(String from) throws RejectException;
	
	/**
	 * Called once for every RCPT TO during a SMTP exchange.
	 * This will occur after a from() call.
	 */
	public void recipient(String recipient) throws RejectException;
	
	/**
	 * Called when the DATA part of the SMTP exchange begins.
	 */
	public void data(InputStream data) throws RejectException, TooMuchDataException, IOException;
}</pre>

	<p>
		For every message delivery, SubEthaSMTP will call your Factory to create
		a MessageHandler.  The from(), recipient(), and data() methods will be
		called during each stage of the SMTP transaction.
		If multiple messages are delivered within a single SMTP session (via the RSET
		command), multiple MessageHandlers will be created.
	</p>

	<h3>Higher-Level Help</h3>
	<p>
		If you simply wish to receive one copy of each message/recipient combination,
		the SimpleMessageListener will help you.
	</p>
	
<pre>SMTPServer smtpServer = new SMTPServer(new SimpleMessageListenerAdapter(myListener));
smtpServer.start();</pre>
	
	<p>
		The SimpleMessageListener is easy to implement:
	</p>
	
<pre>public interface SimpleMessageListener
{
	/**
	 * Called once for every RCPT TO during a SMTP exchange.  Each accepted recipient
	 * will result in a separate deliver() call later.
	 */
	public boolean accept(String from, String recipient);

	/**
	 * When message data arrives, this method will be called for every recipient
	 * this listener accepted.
	 */
	public void deliver(String from, String recipient, InputStream data)
			throws TooMuchDataException, IOException;
}</pre>
	
	<p>
		Your listener simply accept()s any recipients it cares about, and
		the SMTP server will deliver() an input stream of the message data.
		Any recipients which are not accepted by a listener will be rejected.
	</p>
	
	<p>
		Beware, however, that delivering mail to multiple
		recipients requires that the entire message be buffered as it is read by the
		first consumer.  The buffer will start to memory, then switch to disk if the
		size exceeds a threshold.
	</p>

	<p>
		Look at the
		<a href="http://subethasmtp.tigris.org/source/browse/*checkout*/subethasmtp/trunk/smtp/src/org/subethamail/wiser/Wiser.java">source code</a>
		for <a href="wiser.html">Wiser</a> 
		to see a simple example of how to implement SimpleMessageListener.deliver() so that 
		it receives a message and converts it into a JavaMail MimeMessage object.
	</p>
	
	<h3>Authentication</h3>
	<p>
		SubEtha SMTP supports the SMTP AUTH commands through a factory interface similar to
		the MessageHandlerFactory.  For convenience, a pluggable authenticator implementation
		that supports PLAIN and LOGIN is provided with the distribution.
	</p>

<pre>SMTPServer smtpServer = new SMTPServer(myMessageHandlerFactory);
smtpServer.setAuthenticationHandlerFactory(new EasyAuthenticationHandlerFactory(myUsernamePasswordValidator));
smtpServer.start();</pre>

	<p>
		If you do not explicitly set an AuthenticationHandlerFactory, SMTP AUTH will not
		be advertised or supported.  See the javadocs for AuthenticationHandlerFactory for
		more information.
	</p>
	
	<h2>Threading</h2>
	<p>
		SubEthaSMTP is a multithreaded server.  You may change settings on a stopped server
		(ie the # of simultaneous connections allowed) but not after calling start().  Each
		SMTP connection will be serviced by a new thread.
	</p>
	
	<h2>Support</h2>
	<p>
		If you have any bug reports, questions or comments about SubEtha SMTP, it's best that
		you bring these issues up on the 
		<a href="http://subethasmtp.tigris.org/project_lists.html">Mailing Lists</a> and
		not email the authors directly.
	</p>

	<h2>Spec Compliance</h2>

	<p>
		For now, we have just focused on implementing just the minimal 
		required aspects of <a href="http://rfc.net/rfc2821.html#s4.5.1" target="_new">RFC 2821</a>.
		We also return SMTP status responses that mimic what Postfix returns.
	</p>
	
	<p>
		Thanks to a contribution from 
		<a href="mailto:mike REPLACEWITH@ wildpaner.com">Michael Wildpaner</a>, 
		we now support the 
		<a href="http://rfc.net/rfc2487.html">StartTLS specification</a>.
	</p>

	<p>
		Thanks to a contribution from 
		<a href="mailto:mrctrevisan REPLACEWITH@ yahoo.it">Marco Trevisan</a>, 
		we now support the 
		<a href="http://rfc.net/rfc2554.html">SMTP AUTH specification</a>.
	</p>

<script type="text/javascript"><!--
google_ad_client = "pub-3899545862839569";
google_ad_width = 468;
google_ad_height = 60;
google_ad_format = "468x60_as";
google_ad_type = "text_image";
//2007-06-21: wide subethasmtp tigris.org
google_ad_channel = "6417060131";
google_color_border = "444400";
google_color_bg = "CCCC99";
google_color_link = "444400";
google_color_text = "3D81EE";
google_color_url = "FF0000";
//-->
</script>
<script type="text/javascript"
  src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
</script>

</div>
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
</script>
<script type="text/javascript">
_uacct = "UA-952332-3";
urchinTracker();
</script>
</body>
</html>
